home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / smaltalk / manchest.lha / MANCHESTER / usenet / st80_pre4 / pretty-print / smalltalkToTexMacro.doc < prev    next >
Text File  |  1993-07-24  |  29KB  |  894 lines
  1. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2. %%%%%%%%%%%%%%%                           %%%%%%%%%%%%%%%%%%%%%%
  3. %%%%%%%%%%%%%%%  smalltalkToTexMacro.doc  %%%%%%%%%%%%%%%%%%%%%%
  4. %%%%%%%%%%%%%%%                           %%%%%%%%%%%%%%%%%%%%%%
  5. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  6.  
  7.  
  8. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  9. %%%%%%%%  FAST START  %%%%%%%%%%
  10. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11.  
  12.  
  13. % If you want to get started really quickly just type:
  14. %    tex example1.tex
  15. %
  16. % alternatively if you have the latex or texinfo formats/macros
  17. % you can type:
  18. %    latex example2.latex
  19. %    tex example3.texinfo
  20. %
  21. % 
  22.  
  23. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  24. %%%%%%%% INTRODUCTION %%%%%%%%%%
  25. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  26.  
  27.  
  28. % SmalltalkToTex can take a standard chunk format file and format
  29. % it VERY NICELY and INFORMATIVELY for printing. You can either
  30. % print a Smalltalk file independently (a source listing) or
  31. % include the Smalltalk code in another TeX document.
  32.  
  33. % These macros will enable you to:
  34. %
  35. %     * print: class name, class hierarchy, version, 
  36. %           print-time, and page numbers in headers and footers.  
  37. %
  38. %     * recognize and format comments, method categories, message
  39. %           selectors and parameters, and special characters
  40. %
  41. %     * do some unusual nice formatting: methods will tend not to
  42. %           break between pages, long lines will wrap indented
  43. %
  44. %     * print your document in multiple ways: one or two column,
  45. %           different section formatting, different headers, etc.
  46. %
  47. %     * communicate information to your main document: for
  48. %           creating an index of message selectors, table of 
  49. %           contents, etc. 
  50.  
  51. %
  52. % As an example of including code in another document, a document  
  53. % using Texinfo from the Free Software Foundation can (trivially) 
  54. % include your smalltalk code and have a table of contents listing
  55. % all your classes and method categories, and have an index of all 
  56. % your message selectors. 
  57. %
  58. % Latex documents have similar functionality (although indexing would
  59. % depend on your local styles).
  60.  
  61.  
  62. % To get access to all the information in your Smalltalk document
  63. % you will have to add `Chunk Comments' that include commands
  64. % to TeX, but these comments will not affect Smalltalk's ability
  65. % to parse your file. The comments are not required, so a standard
  66. % change log can be printed with almost full functionality.  
  67.  
  68.  
  69.  
  70. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  71. %%%%%%%%%% THE FILES %%%%%%%%%%%
  72. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  73.  
  74. %
  75. % To TeX a Smalltalk file using these macros requires three files.
  76. % The first is the Smalltalk file, the second is a Formatting file,
  77. % and the final file is this file itself. 
  78. %
  79. % The Smalltalk and Formatting files handle different functions.
  80. % The Smalltalk file describes the document (the source text itself
  81. % plus possibly other information), and the Formatting file describes
  82. % how you want it printed. You could have multiple Formatting files
  83. % to print the document in different ways, and one of them could
  84. % be another TeX document that wants to import the Smalltalk source
  85. %
  86.  
  87.  
  88. %%%%%%%%%%%%%%%%%%%%%%%%%%
  89. %%%%% SMALLTALK FILE %%%%%
  90. %%%%%%%%%%%%%%%%%%%%%%%%%%
  91.  
  92.  
  93. % The Smalltalk file can be in two different forms:
  94. %   1) A raw chunk format file  -- no changes
  95. %   2) A chunk format file with TeX comments
  96. %
  97. % The choice between the forms will depend on how whether you want to
  98. % modify your Smalltalk environment in trade for more informative 
  99. % (or simply nicer) printing. In terms of changes to Smalltalk:
  100. %
  101. %   Level 1 requires no changes.
  102. %
  103. %   Level 2 requires adding information when filing out a class, 
  104. %   but it can still be read in normally. 
  105. %
  106. %
  107. % In general if you can file out a class at Level 2, 
  108. % you should do so since reading it in should not be a problem. 
  109. % But if you have a file at level 1, you can print that nicely also.
  110.  
  111.  
  112. %%%%%% Printing Groups - FYI %%%%%%%%%%
  113.  
  114. % There are two groups of printing abilities, the basic-information 
  115. % group (the next word is 'and') and the higher-information 
  116. % group. Actually the basic information group includes knowing 
  117. % where comments start, how to wrap long lines, etc. Higher
  118. % information includes the seperation of methods, what the class
  119. % name is, what to index the method selector under, etc. The 
  120. % seperation between the two levels is not very clear (nor very 
  121. % important as it turns out), but it is mostly that no real
  122. % non-text structure is available at the basic-level. 
  123. %
  124. % Samples of how these information groups are used in formatting
  125. % a file are: 
  126.  
  127. % Basic-information related formatting includes:
  128. %   1) Converting characters ( _ = <leftarrow>)
  129. %   2) Wrapping long lines flush right
  130. %   3) Formatting comments, selectors, etc. 
  131. %   4) Two-column mode
  132. %   and a number of other features...
  133. %
  134. % Higher-information related formatting includes:
  135. %   1) Printing information in headers and footers
  136. %   2) Creating Sectioning 
  137. %   3) Calling indexing routines (none are included but
  138. %      you can call Texinfo or LaTeX routines).
  139. %   4) Class seperation (page breaking between classes)
  140. %   5) Avoiding methods being broken between pages
  141. %
  142. %
  143. % Basic information is needed to print the file nicely at all,
  144. % but the higher information is what we really want.
  145. %
  146.  
  147. %%%%%%%%%% Level-1 Formatting %%%%%%%%%%
  148.  
  149. % From a standard smalltalk chunk format file, all the basic 
  150. % information can be determined and a surprising amount of 
  151. % higher level information as well. 
  152. %
  153. % From a standard file these routines can determine:
  154. %   1) Method Category sections
  155. %   2) Method selectors and parameters
  156. %   3) Method seperations
  157. %   4) Print time
  158. %   5) Page Numbers
  159. %
  160. % But it can not determine:
  161. %   1) Where a new class starts 
  162. %                 (although if classes are seperated by file, 
  163. %                  you can just tell it)
  164. %   2) Class name until after a Method Category section
  165. % ------  Stop the presses, the above two can now be managed
  166. % ------  with \findClasses, see the documentation below
  167. % ------
  168. % ------  also note that the class name is found at the first 
  169. % ------  method category section if you use 
  170. % ------  \useProcessingWithNoClasses or a similar command. 
  171. %   3) Superclass hierarchy
  172. %   4) Version
  173. %   5) Category
  174. %   6) Comment sections
  175. % 
  176. % unless given that information in ChunkComments.
  177. %
  178. %
  179. % As an example a standard file containing a single class
  180. % can format the method category sections, selectors, and
  181. % comments (from the basic level). It can also include the 
  182. % category sections in headers, and print in two-column mode.
  183. % 
  184. % Also, if importanted into another document it can add
  185. % section entries to the table of contents and index entries
  186. % for its message selectors
  187. %
  188. %
  189. % but thats quite enough for most of us.
  190.  
  191.  
  192. %%%% Level 2 Formatting: CHUNK COMMENTS %%%%
  193.  
  194. % We really need to be able to give TeX more information, and
  195. % the way I propose to do that would not hurt the Smalltalk file
  196. % at all.
  197. % If some information is added to the Smalltalk file in chunk
  198. % comments (example: "Chunk Comment"!) 
  199. % than the macro can do some nicer formatting. Chunk commands
  200. % must occur as a normal Smalltalk chunk.
  201. %
  202. % The form of a chunk comment for TeX should be:
  203. %   "\TeXCommand
  204. %   ...various commands...
  205. %   "!
  206. %
  207. %      NOTE: the '!' at the end of a chunk comment
  208. %      is neccesary for Smalltalk/V, but may not be
  209. %      for the other versions. These routines don't
  210. %      care either way.
  211. %
  212. % Inside the TeXCommand block are commands that tell TeX other 
  213. % attributes of the Smalltalk file. They do not tell TeX 
  214. % how to format the file, just information that can not
  215. % be read from the file without understanding Smalltalk code.
  216. %
  217. % An example:
  218. %   "\TeXCommand
  219. %   \startClassDef{NewClass}{Object}
  220. %   \setCategory{Testing}
  221. %   \setVersion{2:10 PM on January 1st, 1991}
  222. %   \endClassDef
  223. %   "!
  224. %
  225. % This states that NewClass is a subclass of Object in category
  226. % Testing with version information 2:10 PM ...1991.
  227. % The \startClassDef and \endClassDef must bracket the class
  228. % information (or the information will go on the wrong page).
  229. %
  230. % You could also add your own commands to this environment,
  231. % for example to include diagrams with your output. The environment
  232. % inside a \TeXCommand block is somewhat limited. That you can not
  233. % use double quotes should be the only rule, but a number of 
  234. % other characters are still active. If this is a problem send
  235. % me a bug report. 
  236. % 
  237.  
  238.  
  239.  
  240. %%%% Level 2 continued: SMALLTALK TeXCommands %%%%
  241.  
  242. % The following are the default available TeXCommands:
  243. %
  244. %   \startClassDef{class}{superclass}
  245. %   \setHierarchy{{superclass}{super-superclass}{s^3}{s^4}}
  246. %   \setCategory{category}
  247. %   \setVersion{string}
  248. %   \setClassSection{section}
  249. %   \setClassSubsection{subsection}
  250. %   \endClassDef
  251. %
  252. %   \class{class}{superclass}
  253. % 
  254. %   \startClassSection{section}
  255. %   \startClassSubsection{subsection}
  256. %
  257. %   \setBangDoubled
  258. %   \setBangModal
  259. %   \readFile
  260.  
  261. % \startClassDef{class}{superclass}
  262. %    sets the current class to <class> and the superclass
  263. %    hierarchy to just <superclass>
  264.  
  265. % \setHierarchy{{s1}{s2}{s3}{s4}}
  266. %    sets the superclass hierarchy to an `array' from s1 to s4
  267. %    parameters can be skipped ex: \setHierarchy{{s1}{s2}}
  268.  
  269. % \setCategory{category}
  270. %    set the category 
  271.  
  272. % \setVersion{string}
  273. %    set the version string (generally a date)
  274.  
  275. % \setClassSection{section}
  276. %    set the section for the class (Definition, Class Methods,etc)
  277. %    by default this is set to Definition at the start of
  278. %    defining a class
  279.  
  280. % \setClassSubsection{subsection}
  281. %    set the class subsection {Private, Accessing, etc.).
  282. %    generally used with Methods
  283.  
  284. % \endClassDef
  285. %    end the class definition and print a header
  286.  
  287. % \class{class}{superclass}
  288. %    is a shortHand for:
  289. %    \startClassDef{class}{superclass}\endClassDef
  290.  
  291. %
  292. % \startSection{section}
  293. % \startSubsection{subsection}
  294. %    start a new section/subsection in the middle of a document.
  295. %    Definition, Methods, Class Methods are usually generated
  296. %    automatically, but if you want a Comment section or a 
  297. %    Summary section you can insert them this way...
  298. %
  299.  
  300.  
  301.  
  302. % The next three commands should generally appear only at
  303. % the start of a document, since they would presumably
  304. % stay constant throughout. They could also be put in the 
  305. % Formatting file
  306. %
  307. %
  308. % \setTabs{num}
  309. %    specify a tab character as representing <num> spaces
  310. %    
  311. %
  312. %
  313. % \setBangDoubled
  314. % \setBangModal
  315. %    change how a `!' is interpretted.
  316. %
  317. % Doubled bangs mean `!'s that occur in text (as opposed to the
  318. % formatting bangs) will be doubled. These I replace with a single
  319. % bang when encountered. 
  320. %
  321. % Modal bangs mean bangs in text are not doubled, but must be
  322. % recognized to be non-special when they occur in text or comment
  323. % strings. 
  324. %
  325. % As far as I can tell:
  326. %    Doubled !s are used by Smalltalk-80 and Smalltalk/V
  327. %    Modal !s are apparently used in Gnu-Smalltalk
  328. %      (That's why I added them)
  329. %
  330. % The default is doubled bangs, so you don't need to bother
  331. % mentioning that in the file. In any case this can be handled in 
  332. % the TeX format file if unmentioned.
  333.  
  334.  
  335.  
  336.  
  337. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  338. %%%%%%%% TeX FORMAT FILE %%%%%%%%
  339. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  340.  
  341.  
  342. % The format file is neccesary to read in this macro file
  343. % and then read in the Smalltalk file; at minimum it would
  344. % contain three lines:
  345. %
  346. %   \input smalltalkToTexMacro.tex
  347. %   \startAndRead{smalltalkChunkFile}
  348. %   \end
  349. %
  350. % The format file can also contain other commands between the
  351. % \input and \startAndRead lines. These will effect how
  352. % the file is read and printed. For example:
  353. %
  354. %   \input smalltalkToTexMacro.tex
  355. %      \standardTwoColumnFormat
  356. %      \linenumberstrue
  357. %   \startAndRead{smalltalkChunkFile}
  358. %   \end
  359. %
  360. % will produce a two column format (on a portrait page) and
  361. % show line numbers. A better example would be
  362. %
  363. %   \input smalltalkToTexMacro.tex
  364. %      \standardTwoColumnFormat
  365. %      \setColumnWidth{4.5in}
  366. %      \setGutterSize{0.3in}
  367. %      \setHeight{6.7in}
  368. %   \startAndRead{smalltalkChunkFile}
  369. %   \end
  370. %
  371. % which would change the page to landscape dimensions: 9.3in by 6.7in.
  372. % and skip the line numbering. 
  373. %
  374. % The format file could also be another document (LaTeX or TeX) document
  375. % and the formatting commands would surround the section where you wanted
  376. % to import the smalltalk code. 
  377. %
  378. %
  379.  
  380.  
  381. %%%% FORMATTING COMMANDS %%%%
  382.  
  383. % The following are the default available formatting commands:
  384. %
  385. % \setBangDoubled
  386. % \setBangModal
  387. % \readFile
  388. %
  389. % the above three were documented in the previous sections
  390. %
  391. % \startAndRead
  392. %
  393. % \findClasses
  394. % \dontFindClasses
  395. %
  396. % \formatMethods
  397. % \dontFormatMethods
  398. %
  399. % \useEightPointFonts
  400. % \useTenPointFonts
  401. % \useLatexFonts
  402. % \useTexFonts  
  403. %
  404. % \useCenteredTitles
  405. % \useLeftThirdTitles
  406. % \useLatexTitles
  407. % \useTexinfoTitles
  408. %
  409. % \standardOneColumnFormat
  410. % \standardTwoColumnFormat
  411. % \standardLatexFormat
  412. % \standardTexFormat
  413. % \standardTexinfoFormat
  414. %
  415. % \fromTexDocument
  416. % \fromLatexDocument
  417. % \fromTexinfoDocument
  418. %
  419. % \linenumberstrue
  420. % \linenumbersfalse
  421. %
  422. % \setColumnWidth{width}
  423. %
  424. % \useOneColumnOutput
  425. % \useTwoColumnOutput
  426. %
  427. % \useSimpleFooter    , ...B
  428. % \useOneColumnFooter 
  429. % \useTwoColumnFooter , ...B
  430. %
  431. % \setGutterSize{gutter}
  432. % \setHeight{height}
  433. % \setOffset{xoff}{voff}
  434.  
  435.  
  436. % There could be many additions and revisions to the formatting 
  437. % commands depending on your personal preferences 
  438.  
  439. % \startAndRead
  440. %     not likely to change this. Set up smalltalk verbatim mode
  441. %     and read in the file
  442. %
  443. % \findClasses
  444. % \dontFindClasses
  445. %     \findClasses will turn on attempting to find the start 
  446. %     of a class definition and use the \class command if it 
  447. %     finds it. This should only be used with files that don't
  448. %     have TeXCommands in it (since they already mention the
  449. %     beginning of a class). Also, the very first class in a file 
  450. %     is not found by this routine, so say \class{file}{super} before
  451. %     the \startAndRead for that class.
  452. %
  453. %     \findClasses will fail if a comment (without a ! at the end)
  454. %     precedes the class start. I do not know how much it slows
  455. %     down the program. The default is \dontFindClasses.
  456.  
  457.  
  458. % \formatMethods
  459. % \dontFormatMethods
  460. %     \formatMethods will find the start of method headers and
  461. %     process the selector and parameters. It finishes and calls
  462. %     \doneMethod with token strings set up to be used for
  463. %     formatting, indexing, etc. Generally you would use one 
  464. %     of the default \doneMethod-s, but it is easy to modify
  465. %     them.
  466. %
  467.  
  468.  
  469. % \useEightPointFonts
  470. % \useTenPointFonts
  471. %    set up the fonts for eight and ten point text
  472. %    includes setting the line spacing and skip sizes
  473. %  
  474. % \useLatexFonts
  475. % \useTexFonts  
  476. %    use the current Latex or Tex fonts for TeXing the Smalltalk
  477. %    source. Doesn't affect line spacing, or math fonts
  478. %  
  479. %    \useTexFonts makes all fonts the same size, although
  480. %    different styles, so it is not very useful. If you
  481. %    are calling from a TeX document, preferably use the 
  482. %    point size commands or define your own font
  483. %    format. There is no \useTexinfoFonts since that would
  484. %    make even less sense (at least to me)
  485. % 
  486.  
  487.  
  488. % \useCenteredTitles
  489. % \useLeftThirdTitles
  490. %    set standard formats for the display macros:
  491. %       \classDefined     is called by the \endDefClass command
  492. %       \printTitle       used by the default classDefined
  493. %       \metaMethods      found a !<Class> class methods!
  494. %       \classMethods     found a !<Class> methods!
  495. %       \metaMethodsCat   found a !<Class> class methodsFor: '<cat>'!
  496. %       \classMethodsCat  found a !<Class> methodsFor: '<cat>'!
  497. %       \doneMethod       found and processed a method header 
  498. %
  499. %    left third looks better in twoColumn formats (since Smalltalk
  500. %    lines tend to be short)
  501. %
  502. % \useLatexTitles
  503. %    causes the above formats to call the latex \section (for \printTitle)
  504. %    and \subsection (for \...Methods...) commands. These also
  505. %    call a \setparstuff after the LaTeX commands to fix the paragraphs
  506. %    for the code. If you want different LaTeX calls, just make
  507. %    a new version of this macro, or redefine the displaying macros
  508. %
  509. % \useTexinfoTitles
  510. %    similar to above but for Texinfo.
  511.  
  512. % \useProcessingWithNoClasses
  513. %    alternate processing of \...Methods... that make sense if no
  514. %    class groupings are available. Should be called after one of the
  515. %    above routines. 
  516. %
  517. % \useAlternateDoneMethodA
  518. %    alternate processing of \doneMethod that ignores multiple lines
  519. %    after the message header, and creates index entries for Texinfo.
  520. %    This is mostly as an example of alternate methods.
  521.  
  522.  
  523. % \standardOneColumnFormat
  524. % \standardTwoColumnFormat
  525. % \standardLatexFormat
  526. % \standardTexFormat
  527. % \standardTexinfoFormat
  528. %    sets a number of variables that make sense for printing
  529. %    a useOneColumnOutput, useTwoColumnOutput, or including in a Latex
  530. %    file. Find the macros below to see what they set.
  531.  
  532. %
  533. % \fromTexDocument
  534. % \fromLatexDocument
  535. % \fromTexinfoDocument
  536. %    sets up for importing into another document
  537. %    all automatically call the above \standard equivalent
  538. %
  539.  
  540. % \linenumberstrue
  541. % \linenumbersfalse
  542. %    turns on or off printing line numbers from start of document
  543. %    You could reset the line number at each method by setting
  544. %    \lineno=1 in a modified version of \doneMethod
  545.  
  546. % \setColumnWidth{width}
  547. %    sets each text column on the page to width, if
  548. %    your page is already set up (calling from another
  549. %    document) you should call this routine with your 
  550. %    default value to set the hanging paragraph values
  551. %
  552.  
  553.  
  554.  
  555. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  556. %% The next set of commands are output related and should     %%
  557. %% not be used with LaTeX or inside your own document format, %%
  558. %% unless you understand their macros fully.                  %%
  559. %%                                                            %%
  560. %% Do read the section FOOTERS/HEADERS and examine the footer %%
  561. %% macros to see how to get page information into your        %%
  562. %% documents footers and headers. I haven't tested yet whether%%
  563. %% these work in LaTeX                                        %%
  564. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  565.  
  566. % \useOneColumnOutput
  567. % \useTwoColumnOutput
  568. %    set the output routines two one column or two columns
  569.  
  570.  
  571. % \setGutterSize{gutter}
  572. %    sets the gutter (of a multi-column format)
  573. %
  574. %    the total page size will be:  
  575. %         total = width + ((columns-1) * (gutter + width))
  576. %
  577. % \setHeight{height}
  578. %    the height of the page
  579. %
  580. % \setOffset{xoff}{voff}
  581. %    move the offset of the printed page by:
  582. %       xoff to the right
  583. %       voff downward
  584.  
  585.  
  586. % \useSimpleFooter    , ...B
  587. % \useOneColumnFooter 
  588. % \useTwoColumnFooter , ...B
  589. %    set the footer of the page, useSimpleFooter only uses a page
  590. %    number and a print time, the other two are fancier.
  591. %
  592. %    fancy headers can be defined also, using the same methods
  593. %    as for the footers, but setting \headline instead of \footline
  594. %
  595.  
  596.  
  597. % FOOTERS/HEADERS:
  598. %    To reference values passed by Smalltalk (class, version, etc)
  599. %    in footer or headers you should use \page... commands. 
  600. %    These will produce the right values at the time the 
  601. %    footer/header is printed.
  602. %
  603. %    If a \page... command doesn't exist for what you want (i.e.
  604. %    a different kind of \pageHierarchy) you can create one by looking
  605. %    at the other \page... macros and using \get... macros in
  606. %    your new one. 
  607. %
  608. %    Footers are created when the page is output and look up 
  609. %    information through items called `marks' that were put on
  610. %    the page when it was read in. This becomes moderately 
  611. %    complicated, but is hidden away in the lower level macros.
  612. %
  613.  
  614.  
  615.  
  616.  
  617. %%%%%%%%%%%%%%%%%%%%%%%
  618. %%%%% Other files %%%%%
  619. %%%%%%%%%%%%%%%%%%%%%%%
  620.  
  621. % Although two main files will work for typesetting a Smalltalk
  622. % document, what can work better is to have a log file written
  623. % by Smalltalk listing the files of the most recent filed classes 
  624. % or methods. This file only contains \readFile{filename} 
  625. % commands where the filename-s are for the recently filed-out
  626. % files. If you just filed out:
  627. %     Behavior.st
  628. %     Class.st 
  629. %     MetaClass.st 
  630. %
  631. % a file named fromSmalltalk.tex (for example) would contain:
  632. %    \readFile{Behavior.st}
  633. %    \readFile{Class.st}
  634. %    \readFile{MetaClass.st}
  635. %
  636. % and a format file texSmalltalk.tex would contain at least:
  637. %    \input smalltalkToTexMacro.tex
  638. %    \startAndRead{fromSmalltalk.tex}
  639. %    \end
  640. %
  641. % this would enable you to quickly TeX and print texSmalltalk.tex
  642. % independent of what you just filed out. All the files
  643. % would be formatted together, but the macros reset page numbers
  644. % correctly anyway.
  645. %
  646.  
  647.  
  648. % The command:
  649. %
  650. % \readFile{filename}
  651. %    this reads in another Smalltalk file for typesetting 
  652. % 
  653.  
  654.  
  655. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  656. %%%%%% Using from insidea a LaTeX or TeX document %%%%%%%%%
  657. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  658.  
  659.  
  660.  
  661. % If you are using this macro from another document either
  662. % in TeX, LaTeX, or Texinfo you should be aware of the
  663. % following:
  664.  
  665. % The commands \fromTexDocument, \fromLatexDocument, and
  666. % \fromTexinfoDocument handle most of these aspect for you,
  667. %  but you may want to change the environment.
  668.  
  669. % (Whenever I refer only to LaTeX in this section, I
  670. %  probably meant to refer to importing from any document
  671. %  environment but was lazy when I wrote it).
  672.  
  673. % Don't use the commands that would damage your document
  674. % environment (like resetting the ship-out functions),
  675. % unless you really want it to. In LaTeX these output
  676. % commands should produce errors anyway. These were
  677. % marked as special when mentioned above
  678.  
  679.  
  680. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  681. %%%%%%% Class Ejecting %%%%%%%
  682. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  683.  
  684. % \classEject is called when ever a new class is started,
  685. % but the first time is is called it does nothing, and 
  686. % `loads' its next eject form from \nextClassEject. 
  687. % \classEject should keep this form -- if you want to
  688. % eject the page before starting the Smalltalk code,
  689. % put the eject in your normal code (probably you wouldn't
  690. % think to do otherwise, but it is important)
  691. %
  692. %
  693. % In a normal TeX document, \classEject does what you want
  694. % it to do.
  695. % In a LaTeX document you should redefine \nextClassEject to
  696. % \clearpage or \cleardoublepage or \cleardoublepageLeft
  697. % 
  698. % \cleardoublepageLeft guarantees the following text will
  699. % be on a left hand page (inserting blank pages if neeeded).
  700. % It is defined (far) below if you want to put it with your
  701. % own macros, or need to use it before you have read in this file.
  702. %
  703. %
  704. % \fromLatexDocument defines \nextClassEject as \clearpage
  705.  
  706.  
  707. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  708. %%%%%%%% Mark routines %%%%%%%
  709. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  710.  
  711.  
  712. % 
  713. % These macros communicate to the output routine through 
  714. % \mark-s. This will interfere with LaTeX and possibly
  715. % your own TeX mark routines. This is assumed to be a problem
  716. % and I call \marksOff in the \from... commands. 
  717. %
  718. % If you leave marks off and don't call your marking routines,
  719. % you will simply leave the state of the marks constant.
  720. %
  721. % If you communicate to your mark routines during the smalltalk
  722. % file input, you can use \print... commands to gain access to
  723. % the smalltalk information.
  724. %
  725. %
  726. % If you instead want different output routines during the smalltalk
  727. % section and want to use the \page... commands in them, you can
  728. % turn \marksOn during that period.
  729. %
  730. %
  731. % Turning the \marksOn is not a problem as long as the two mark 
  732. % output environments are kept seperate. This only requires
  733. % ejecting your old page before starting up the smalltalk file
  734. % and ejecting the last smalltalk page before returning to your
  735. % regular text. All the \page... commands will be available during
  736. % the smalltalk pages, and the two types of marks won't interfere.
  737. %
  738. % If you turn \marksOn, you will need to change your output
  739. % routines to use them. If you wrote your own, you know what
  740. % to fix.
  741. % If you are using LaTeX your file will need to do the following:
  742. %
  743. %  eject the page
  744. %
  745. %    1) Save the old LaTeX mark values
  746. %    2) change the output routines to use the desired information
  747. %       from the Smalltalk file
  748. %
  749. %  read in the Smalltalk file
  750. %  eject the last Smalltalk page
  751. %
  752. %    3) Remark with the old values
  753. %    4) Restore the old mark routines
  754. %
  755. %  continue reading your normal file 
  756. %
  757. % The last aspect 4) should be done by putting \begingroup before
  758. % 1) and \endgroup after the eject (before or just after 3). Example
  759. % code that does all this is for LaTeX:
  760. %
  761. %%%
  762. %%% \begingroup
  763. %%% %%% Save the old formatting commands, and set new ones
  764. %%%    \xdef\saveLeft{\leftmark}  %must be global since it will be accessed
  765. %%%    \xdef\saveRight{\rightmark}%outside the group
  766. %%%
  767. %%%    \def\leftmark{\pageClass\ \ddash\ Left}          %or whatever you want
  768. %%%    \def\rightmark{Right\ \ddash\ \pageVersion}      %
  769. %%%
  770. %%%
  771. %%%    \input smalltalkToTexMacro.tex
  772. %%%    \fromLatexDocument
  773. %%%    \marksOn
  774. %%%    %% other commands... 
  775. %%%    \startAndRead{fromSmalltalk.tex}
  776. %%%
  777. %%%    \eject
  778. %%%
  779. %%% %%% Restore the old format
  780. %%%    \markboth{\saveLeft}{\saveRight}
  781. %%%
  782. %%% \endgroup%return \leftmark, \rightmark back to normal
  783. %%%
  784. %
  785.  
  786.  
  787. % ERRORS: If you see a `extra \or' error it is probably from
  788. % not ejecting your page before the smalltalk page. My mark
  789. % routines use a lot of \or-s in them.
  790.  
  791.  
  792. %%%%% Summary for LaTex / other marking routines %%%%%%
  793.  
  794. % To summarize the LaTeX options, you could have:
  795. %   1) \marksOff, and Smalltalk titles (like \useCenteredTitles)
  796. %   2) \marksOff, and LaTeX/Your sectioning
  797. %   3) \marksOn, and Smalltalk titles
  798.  
  799. % For: 
  800. %    1) you don't need to do anything special, but you lose access 
  801. %       to output time access to Smalltalk information
  802. %       
  803. %    2) you also don't need to do anything special, and get access 
  804. %       to the info that was passed to the LaTeX sectioning, and
  805. %       which can include any of the \print... commands
  806. %    
  807. %    3) you need to make sure the mark environments are separated, 
  808. %       make new headers and footers for the style, and then return
  809. %       the environment back when returning to LaTeX. You have access
  810. %       to all the smalltalk values, but can't increment LaTeX sectioning
  811. %       (you do have access to the LaTeX information through \the... 
  812. %       commands.
  813.  
  814. % To get the option use the following commands (assuming LaTeX) 
  815. %    1) \fromLatexDocument
  816. %
  817. %    2) \fromLatexDocument
  818. %       \useLatexTitles
  819. %
  820. %    3) \fromLatexDocument
  821. %       \marksOn
  822. %
  823.  
  824.  
  825. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  826. %%%%%%% Probably Irrelevant LaTeX Option %%%%%%%%%%%
  827. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  828.  
  829.  
  830. % At the moment I don't know why, but you might want to
  831. % have the LaTeX marking command flow throught these 
  832. % macros commands. This would have the LaTeX \section, 
  833. % \subsection... commands calling the smalltalk routines
  834. % and putting extra information into the smalltalk marks.
  835. % Then when LaTeX reads the marks, (via \leftmark \rightmark),
  836. % you would have access to all the information possible.
  837. %
  838. % So to summarize, this option uses LaTeX sectioning and
  839. % output but flows through the smalltalk mark system...
  840. % Documentation for the will be in "latexdoublemark.tex" and
  841. % you should look at the routines called from that document
  842.  
  843.  
  844.  
  845. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  846. %%%%%%% Running TeX %%%%%%%%%%%
  847. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  848.  
  849.  
  850. %
  851. % I will not attempt to describe how to use TeX at your
  852. % site, you hopefully have documentation there. I will
  853. % just make some comments about running TeX with these
  854. % macros.
  855.  
  856. % You should not be surprised if TeX complains about
  857. % `Underfull \hbox'. This is from wrapping long lines.
  858. % I set the tolerance low enough so that TeX tries
  859. % to make the wrapping compact and nice, so if TeX
  860. % can't succeed it complains and tries again. The second
  861. % pass I set the tolerance to infinity, so TeX won't 
  862. % mark you output file in any case. Since the bad
  863. % wrapping is not really bad for our purposes, you 
  864. % can pretty much ignore it. 
  865.  
  866. % Also TeX may complain about `Underfull \vbox' 
  867. % because it did not like any of the breaks it
  868. % found for the current page. This also is not
  869. % really a problem, but it can be remedied 
  870. % by changing the \sectionBreak-s vskip glue
  871. % to allow more stretching and shrinking. This
  872. % also has a benefit of making methods less
  873. % likely to break across a page. 
  874. %
  875. % You could also turn on \raggedbottom to 
  876. % aleviate this problem, if you prefer the
  877. % resulting page breaks. 
  878.  
  879.  
  880. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  881. %%%%%%% Final Documentation %%%%%%%%%%%
  882. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  883.  
  884. % 
  885. % The examples are the best documentation for using
  886. % these macros and the printouts for what they do,
  887. % but if you need to modify them in any way, you will
  888. % have to read the sections below.
  889. %
  890. % I tried order the groups from most likely to modify to least
  891. % likely to modify, but they are grouped by function.
  892. % 
  893.  
  894.